filename

Type

property

Summary

Specifies the file associated with a player or image.

Syntax

set the filename of {<image> | <player>} to {<filePath> | <URL>}

Description

Use the filename property to reference a separate file that holds the data for an image or player that's a referenced control.

The contents of an image can reside either in the stack or in a separate file. If an image's filename is empty, the image uses its own data, which resides in the stack, instead of loading a separate file. (You can import an image with the import command, or paint an image with the paint tools. ) Setting an image's filename property to the name and location of a file deletes the previous contents of the image.

Using an image from a separate file reduces memory use, since the image does not need to be loaded into memory unless it is in use. But it increases the time it takes to go to a card containing the image, since the file must be loaded from the disk it's on or from the Internet.

The contents of a player must reside in a separate file that is specified in the player's filename property. If a player's filename is empty, the player does not display any data. The file specified by the filePath or URL must be in a format supported by AVFoundation on Mac and DirectShow on Windows.

    set the filename of player \"My Player\" to \"SecondMovie. mov\"
    set the currentTime of player \"My Player\" to zero

If you specify a URL for a streaming a movie file, LiveCode displays the movie sequentially as it downloads. Otherwise, LiveCode must download the entire file before you can play it. To pre-fetch a file from the Internet in order to speed up access to it, use the load command before visiting the card that holds the player or image that references the file's URL.

You can use the "New Referenced Control" submenu in the File menu to create a new image or player which references the contents of a file you specify. You can also set the filename to an absolute path or relative path by changing the Source field in the image's or player's property inspector.

To take full advantage of Hi-DPI, images must be provided at appropriate sizes for different densities. This can be done by having multiple image files in the same location named appropriately (with the image object referencing the image file at the natural density). The naming convention is as follows:

• @ultra-low.
• @ultra-low. - 0.25x
• @extra-low. - 0.5x
• @low. - 0.75x
• @medium. / . - 1x
• @high. - 1.5x
• @extra-high. / @2x - 2x
• @ultra-high. - 4x

When an image is required, the current scale factor is rounded up to the nearest standard density (one of 0.25, 0.5, 0.75, 1, 1.5, 2 and 4). The image with the lowest scale factor that is greater or equal to the nearest standard density is then selected. For example, if the scale factor is 1.75 and there is an extra-high image available, then that is used. Images should be created at appropriately scaled pixel size. If the natural size of an image is x points wide and y points high, the scaled versions should be x scale pixels wide and y scale pixels high in order to have the same natural size. You should take care that the natural size of the image scales to integer pixel sizes, as the logical point size of the image is rounded up to the nearest integer. If this is not practical for a given image, you may need to design your apps to handle slightly different resulting image sizes.

Examples

set the filename of image "Animation" to "/HD/Projects/blipvert.gif"

set the filename of last player to "http://www.example.com/myMovie.mov"

Value

Name	Type	Description
value		The filename of an image or player specifies either a file path or a URL. A file path specifies the name and location of the file. If you specify a name but not a location, LiveCode assumes the file or relative paths are from the defaultFolder or the folder the stack is saved in. A URL specifies the name and location of a file on your system or anywhere on the Internet. By default, the filename property of newly created images and players is set to empty.
the result		If the filename of a player is set to an invalid file/URL, or to a corrupted file, then an error message of "could not create movie reference" is returned in the result. Otherwise, empty is returned in the result. A useful rule of thumb is for images to have natural width and height values that are multiples of four, this way all the supported densities result in integer pixel sizes for each version of the image, and the resulting image has the same logical point size as all display densities.

Related

command: import

function: tempName, shortFilePath

message: saveStackRequest

property: fileType, constantMask

Compatibility and Support

Introduced

LiveCode 1.0

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile